<!DOCTYPE html>

<!--[if lt IE 7 ]><html class="ie ie6" lang="en"> <![endif]-->
<!--[if IE 7 ]><html class="ie ie7" lang="en"> <![endif]-->
<!--[if IE 8 ]><html class="ie ie8" lang="en"> <![endif]-->
<!--[if (gte IE 9)|!(IE)]><!--><html lang="en"> <!--<![endif]-->
    <head>
        <meta charset="utf-8">
        <title>A New Hope: Plugin Layout with Pathogen / Learn Vimscript the Hard Way</title>
        <meta name="description" content="">
        <meta name="author" content="Steve Losh">
        <!--[if lt IE 9]>
            <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
        <![endif]-->

        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">

        <link href="/static/styles/skeleton/base.css" rel="stylesheet" type="text/css" />
        <link href="/static/styles/skeleton/skeleton.css" rel="stylesheet" type="text/css" />
        <link href="/static/styles/skeleton/layout.css" rel="stylesheet" type="text/css" />

        <link href="/static/styles/tango.css" rel="stylesheet" type="text/css" />
        <link href="/static/styles/style.less" rel="stylesheet/less" type="text/css" />

        <script type="text/javascript" src="/static/scripts/less.js"></script>
    </head>

    <body class="">
        <div class="container">
            <header class="sixteen columns">
                <h1><a href="/">Learn Vimscript the Hard Way</a></h1>
            </header>

            
    <section class="nav three columns">
        
<ul>
<li><a href="#a-new-hope-plugin-layout-with-pathogen">A New Hope: Plugin Layout with Pathogen</a><ul>
<li><a href="#runtimepath">Runtimepath</a></li>
<li><a href="#pathogen">Pathogen</a></li>
<li><a href="#being-pathogen-compatible">Being Pathogen-Compatible</a></li>
<li><a href="#exercises">Exercises</a></li>
</ul>
</li>
</ul>


        <div class="prevnext">
            
                <a class="prev" href="42.html">&laquo; Prev</a>
            
            
                <a class="next" href="44.html">Next &raquo;</a>
            
        </div>
    </section>

    <section class="content twelve columns offset-by-one">
        <div> 
<h1 id="a-new-hope-plugin-layout-with-pathogen">A New Hope: Plugin Layout with Pathogen</h1>
<p>Vim's vanilla layout for plugin files makes sense if you're just adding a file
here and there to customize your own Vim experience, but turns into a mess when
you want to use plugins other people have written.</p>
<p>In the past, when you wanted to use a plugin someone else wrote you would
download the files and place them, one-by-one, into the appropriate directories.
You could also use <code>zip</code> or <code>tar</code> to do the placing for you.</p>
<p>There are a few significant problems with this approach:</p>
<ul>
<li>What happens when you want to update a plugin?  You can overwrite the old
  files, but how do you know if the author deleted a file that you now need to
  delete by hand?</li>
<li>What if two plugins happen to have a file with the same name (like <code>utils.vim</code>
  or something generic like that)?  Sometimes you can simply rename it, but if
  it's in <code>autoload/</code> or another directory where the names matter you've got to
  edit the plugin yourself.  Not fun.</li>
</ul>
<p>People came up with several hacks to try to make things easier, like Vimballs.
Luckily we don't need to suffer through these ugly hacks any more.  <a href="http://tpo.pe/">Tim Pope</a>
created the wonderful <a href="http://www.vim.org/scripts/script.php?script_id=2332">Pathogen</a> plugin that makes managing multiple plugins
a breeze, as long as plugin authors structure their plugins in a sane way.</p>
<p>Let's take a quick look at how Pathogen works and what we need to do to make our
plugin compatible.</p>
<h2 id="runtimepath">Runtimepath</h2>
<p>When Vim looks for files in a specific directory, like <code>syntax/</code>, it doesn't
just look in a single place.  Much like <code>PATH</code> on Linux/Unix/BSD systems, Vim
has the <code>runtimepath</code> setting which tells it where to find files to load.</p>
<p>Create a <code>colors</code> directory on your Desktop.  Create a file in that directory
called <code>mycolor.vim</code> (you can leave it empty for this demonstration).  Open Vim
and run this command:</p>
<pre class="codehilite"><code class="language-vim">:color mycolor</code></pre>


<p>Vim will display an error, because it doesn't know to look on your Desktop for
files.  Now run this command:</p>
<pre class="codehilite"><code class="language-vim">:set runtimepath=/Users/sjl/Desktop</code></pre>


<p>You'll need to change the path to match the path of your own Desktop, of course.
Now try the color command again:</p>
<pre class="codehilite"><code class="language-vim">:color mycolor</code></pre>


<p>This time Vim doesn't throw an error, because it was able to find the
<code>mycolor.vim</code> file.  Because the file was blank it didn't actually <em>do</em>
anything, but we know it was found because it didn't throw an error.</p>
<h2 id="pathogen">Pathogen</h2>
<p>The Pathogen plugin automatically adds paths to your <code>runtimepath</code> when you load
Vim.  Any directories inside <code>~/.vim/bundle/</code> will each be added to the
<code>runtimepath</code>.</p>
<p>This means that each directory inside <code>bundle/</code> should contain some or all of
the standard Vim plugin directories, like <code>colors/</code> and <code>syntax/</code>.  Vim can now
load files from each of those directories, which makes it simple to keep each
plugin's files in its own directory.</p>
<p>This makes it trivial to update plugins.  You can simply blow away the old
plugin's directory entirely and replace it with the new version.  If you keep
your <code>~/.vim</code> directory under version control (and you should) you can use
Mercurial's subrepos or Git's submodules to directly check out each plugin's
repository into <code>~/.vim/bundle/</code> and then update it with a simple <code>hg pull; hg
update</code> or <code>git pull origin master</code>.</p>
<h2 id="being-pathogen-compatible">Being Pathogen-Compatible</h2>
<p>When we write our Potion plugin we want to let our users use it with Pathogen.
Doing this is simple: we simply put our files in the appropriate directories
inside the plugin's repository!</p>
<p>Our plugin's repository will wind up looking like this:</p>
<pre class="codehilite"><code class="language-text">potion/
    README
    LICENSE
    doc/
        potion.txt
    ftdetect/
        potion.vim
    ftplugin/
        potion.vim
    syntax/
        potion.vim
    ... etc ...</code></pre>


<p>We can put this on GitHub or Bitbucket and users can simply clone it down into
<code>bundle/</code> and everything will just work!</p>
<h2 id="exercises">Exercises</h2>
<p>Install <a href="http://www.vim.org/scripts/script.php?script_id=2332">Pathogen</a> if you haven't already done so.</p>
<p>Create a Mercurial or Git repository for your plugin, called <code>potion</code>.  You can
put it anywhere you like and symlink it into <code>~/.vim/bundle/potion/</code> or just put
it directly in <code>~/.vim/bundle/potion/</code>.</p>
<p>Create <code>README</code> and <code>LICENSE</code> files in the repository and commit them.</p>
<p>Push the repository up to Bitbucket or GitHub.</p>
<p>Read <code>:help runtimepath</code>.</p></div>

        <div class="prevnext">
            
                <a class="prev" href="42.html">&laquo; Previous</a>
            
            
                <a class="next" href="44.html">Next &raquo;</a>
            
        </div>
    </section>


            <footer class="sixteen columns">
                Made by <a href="http://stevelosh.com">Steve Losh</a>.

                <a href="/license.html">License</a>.

                Built with
                <a href="http://bitbucket.org/sjl/bookmarkdown/">Bookmarkdown</a>.
            </footer>
        </div>

        
            <script type="text/javascript">
                var _gaq = _gaq || [];
                _gaq.push(['_setAccount', 'UA-15328874-8']);
                _gaq.push(['_trackPageview']);

                (function() {
                 var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
                 ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
                 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
                 })();
            </script>
        

        
            <script type="text/javascript">
                var _gauges = _gauges || [];
                (function() {
                 var t   = document.createElement('script');
                 t.type  = 'text/javascript';
                 t.async = true;
                 t.id    = 'gauges-tracker';
                 t.setAttribute('data-site-id', '4e8f83b7f5a1f546e200000d');
                 t.src = '//secure.gaug.es/track.js';
                 var s = document.getElementsByTagName('script')[0];
                 s.parentNode.insertBefore(t, s);
                 })();
             </script>
        
    </body>
</html>
